{{i18n|Maintaining Packages}}
[[Category:Cherimoya]]

Cherimoya is dependent on a set of precompiled packages. Because the security of all Cherimoya users depend on up-to-date packages, a package maintainer is needed to look out for new versions and security patches.

==What you need==

* Any Linux-based system (Arch or Chakra-based recommended)
* Basic knowledge of how to use Git 
** Here's a [http://www.kernel.org/pub/software/scm/git/docs/gittutorial.html quick tutorial], and the [http://www.kernel.org/pub/software/scm/git/docs/user-manual.html full manual].
* An understanding of how Arch Linux packages work and are made (don't worry, it's extremely easy, more so than MakeFiles)
** [https://wiki.archlinux.org/index.php/Creating_Packages Basic Guide at Arch Wiki] and [https://wiki.archlinux.org/index.php/PKGBUILD PKGBUILD Specification]
* A [https://gitorious.org/ Gitorious] account

There is no registration needed to be a package maintainer for Cherimoya. All you need to do is check versions in the PKGBUILDs against the corresponding AUR/CCR package (or in the case of [[Firefox Addons]], Mozilla's addon site), make changes to the PKGBUILD, and then send a merge request. Just do it whenever you feel like it.

{{Installing Pacman}}

==Installing the Cherimoya Buildsystem==
The Cherimoya Buildsystem is a special chroot environment specially designed for building our packages for any architecture, on any system using GNU utils (Mac OS X, Linux, BSD, etc). It builds any package, signs it, all in a nice clean environment.

First, get the [http://dl.dropbox.com/u/22186524/files/ch-setup.sh installation script]. Then, make it executable with this command:
 chmod +x ch-setup.sh

Make sure you've installed Git, and run this command:
 ./ch-setup.sh '''''repository''''' '''''branch''''' '''''architecture'''''

Where:
*'''''repository''''' is one of the available repositories: {{Codeline|cherimoya}}, {{Codeline|cherimoya-firefox}}, {{Codeline|defense}}, and {{Codeline|offense}},.
*'''''branch''''' can be: <code>master</code> (stable), <code>testing</code> or <code>unstable</code>.
*'''''architecture''''' can be either <code>i686</code> or <code>x86_64</code>.
* If you have commit rights, you should add a fourth parameter: {{Codeline|c}}. To get those rights, read {{link|How to become a packager|how to become a packager}}. Basically, run this: {{Codeline|./c-setup.sh '''''repository''''' '''''branch''''' '''''architecture''''' n}}

The script will ask for your user password. Remember your user must have sudo-rights. Here is an example:

{{Cli|<nowiki>[packager@chakra master]$ ./ch-setup.sh cherimoya master i686

Cherimoya Packager's Chroot Setup Script v0.5.1.0

:: Root                 : /home/iruel/32m/buildroot
:: Chroot Installation  : /home/iruel/32m/buildroot/cherimoya-i686
 
:: Do you want to continue (y/n)</nowiki>{{Cursor}}}}

Check the paths are correct and enter {{Codeline|y}} and {{Keypress|Enter}} to continue. 

''If you ran the script with {{Codeline|c}} as fourth parameter, you will be then asked for your SSH password for Git.''

Once all packages are downloaded and installed, you'll be asked for your password. It is your user password, not root. 

{{Cli|<nowiki>Password:
 
:: configuring system DONE 

User setup

:: adding user: anke DONE 
:: you will be asked to enter a password for the chroot user</nowiki>}}

And later, you will be asked for a new password for the chroot user. You can (and probably should) enter your user password, so your user has the same password in and out of the chroot. Then, enter it again to confirm.

{{Cli|<nowiki>Enter new UNIX password: 
Retype new UNIX password: 
passwd: password updated successfully
 
:: setting up /etc/sudoers DONE 
:: setting up device permissions DONE 
:: unmounting special dirs DONE</nowiki>}}

After that, the script installs all needed scripts, sets up your makepkg-config and fetches all needed PKGBUILDs. You will be asked for your full name and your email (This is for Git, you can use a pseudonym and a fake email).

{{Cli|<nowiki>:: enter your full name (eg, John Smith): Anke Boersma
:: and your email (eg, jsmith@chakra-project.org): abveritas@chakra-project.org
:: finishing... DONE</nowiki>}}

And that's it! You have a chroot created and prepared to manage a repository. You can ('''and should''') repeat the process for a different combination of repository and architecture or, in another folder, for a different branch.

{{Warning|If there were errors during the process, like no Internet connection or wrong password, the script will not stop. That doesn't mean everything is okay. If there were errors, you must run the script again from the beginning. You might get this display:

{{Cli|(k)eep chroot master-x32 and update it?
(d)elete/reinstall chroot master-x32?
(u)ninstall chroot master-x32?
(q)uit this script? {{Cursor}}}}

Where you should choose {{Codeline|d}}. Typing sudo -v into a different terminal might help also with the sudo-password problems.}}

== Adding another chroot ==

The steps to create a new chroot into a current build system is pretty much the same. You just need to skip the steps to install the buildsystem and download the scripts (since you already downloaded it).

Choose a different repository (available ones are {{Codeline|cherimoya}}, {{Codeline|cherimoya-firefox}},{{Codeline|defense}}, and {{Codeline|offense}}.)

{{Cli|<nowiki>[packager@chakra master]$ ./c-setup.sh defense master i686
The chroot master-x32 already exists. Do you want to:

(k)eep chroot master-x32 and update it?
(d)elete/reinstall chroot master-x32?
(u)ninstall chroot master-x32?
(q)uit this script?</nowiki>{{Cursor}}}}

You should type {{Keypress|k}} here.

==Entering the Chroot==
To enter the chroot, use this command (as the normal user):
 cd buildroot
 ./enter-chroot.sh '''<repository>'''

Replacing '''<repository>''' with any installed chroot, such as "cherimoya-i686".

You will then be asked for your chroot user's password. Then, you'll be into the chroot. You will see the chroot content, and the prompt will be in red, so you know when you are into the chroot.

To ensure your chroot is clean and synced before starting to build and add packages, a good practice is to always use these commands after entering your chroot:

 git status # This tells you about the local changes you haven't committed yet. 
 git pull # Updates your Git copy. 
 pacman -Sc 
 pacman -Syu 

==Exiting the chroot==
Just use this command:
 exit

Your prompt should no longer be red.

==Using the Buildsystem==
After entering the chroot, you will see a list of packages in that repository. Enter any of them and edit the PKGBUILDs inside.

===Create a Build Package===
To create a new package, read the [https://wiki.archlinux.org/index.php/Creating_Packages Arch Wiki], and make sure your follow [http://chakra-project.org/wiki/index.php/Packaging_Standards Chakra standards].

If you are porting a build package from the [[User Repositories#CCR|CCR]] or [[User Repositories#AUR|AUR]], check [http://chakra-project.org/wiki/index.php/Packaging_Standards the standards] too, since there are some differences between packages in the CCR and packages in the official repositories.

Once you have the {{Filename|PKGBUILD}} and other needed files ready, put them in a folder with package's name, and put that folder into the right {{Filename|buildroot/'''''repository'''''-'''''branch'''''-'''''architecture'''''/pkgbuilds/}} folder.

===Build a package===
Go into any package folder and use these commands:

 cd <package_name> 
 ../makepkg -rs

The buildsystem's special {{Codeline|makepkg}} script allows package signing, along with other useful extras. The {{Codeline|-rs}} option tells makepkg to get all the dependencies and remove them after building, which is important.

You don't have to worry about package signing unless you have commit support.

===Clean the Package Directory===
Once compiled, clean '''''package_name''''' folder, and just leave the {{Filename|PKGBUILD}} file and any {{Filename|.install}} file, {{Filename|ChangeLog}} or patches. That is, the files that was already in the folder before running {{link|Makepkg}}. Then check what additional files are there or what have you changed:
:<code>git status</code>

There should be no additions, since you have already deleted those files created during the build process. If there is any unexpected untracked file, remove it and run <code>git status</code> again.

Note that when a package successfully compiles, it is moved to {{Filename|_repo/local}}, and the {{Filename|.pkg.tar.xz}} file in package's folder is just a symlink that Git will ignore. That means, you don't need to delete it (but you can).

===Test your package===
If you are working on a package for the same branch and architecture as yours, you ''should'' test it in your own system before submitting it to the Git repositories.

[[Maintaining Packages#Exiting the Chroot|Exit your chroot]], go to {{Filename|buildroot/repository-branch-architecture/packages/local/}}, and install it with:

 cd buildroot/<repository-branch-architecture>/packages/local/ 
 pacman -U <packagefile>.pkg.tar.xz 

Then run it in your system, and once you have checked it works as expected, jump to the next step.

===Upload the PKGBUILD to a fork===
{{Note|If you are allowed to directly commit to Cherimoya's Git repo, just use Git normally. Everything was set up during installation.}}

If you do not have direct commit privileges (which means most people), you should fork our repository, upload your changes to that fork, and send a merge request to contribute your changes to Cherimoya.

First, go to the [https://gitorious.org/cherimoya-packages Cherimoya Packages] page on Gitorious. Create an account, make an [[SSH|ssh key]], and then go back to our page. Click '''Clone Repository''' on the repo you want to submit a change to.

[[File:Gitorious1.png]]

You will end up with a link in the middle of the box, as shown in the image to the right. Copy that link, and put it in place of {{Codeline|<link>}} below:

 git remote add fork <link>

After that, you can commit and add files like any git repo, with the exception of the "push" command:

* {{Codeline|git status}} Just to make sure the changes are correct. 
* {{Codeline|git add '''package_name'''}} Where '''package_name''' is the name of the folder containing the package. You can add more than one folder, or repeat this step for other packages, in case you added more than one. If you are updating an existing build package and didn't add any new file, skip this step. 
* {{Codeline|git commit -am}} Here, write a description of the changes you made. Example: {{Codeline|Added 'package1' and 'package2'}}.. 
* {{Codeline|git push fork master}} This is what actually send the changes to the Git repository. The third argument to Git, the '''branch''', is usually {{Codeline|master}}.

[[File:Gitorious2.png|thumb]]

Once you've pushed your commits, go to your forked repository and click "Request Merge" to send your changes for approval. You're done!

===Upload the PKGBUILD===
If you have direct commit privileges, you can upload the PKGBUILD to Git. Enter the chroot again, and run:

* {{Codeline|git status}} Just to make sure the changes are correct. 
* {{Codeline|git add '''package_name'''}} Where '''package_name''' is the name of the folder containing the package. You can add more than one folder, or repeat this step for other packages, in case you added more than one. If you are updating an existing build package and didn't add any new file, skip this step. 
* {{Codeline|git commit -am}} Here, write a description of the changes you made. Example: {{Codeline|Added 'package1' and 'package2'}}.. 
* {{Codeline|git push origin '''branch'''}} This is what actually send the changes to the Git repository. The '''branch''' is the one your chroot was made for, usually {{Codeline|master}}.

=== Updating an existing package ===
First thing you need to do is to update the PKGBUILD of the application you are updating. Usually this is as simple as checking the CCR or AUR for a newer version of that package. Once you've found an update, just port it over and test it.

In the case of Firefox Addons, it's not difficult either; Check for a newer version at [https://addons.mozilla.org/en-US/firefox/ Firefox's addon site].

When working with PKGBUILDS:

* Change the {{Codeline|pkgver}} variable to its new version, or increase the {{Codeline|pkgrel}} variable if you are rebuilding the same version of the package (i.e. with an additional patch).
* Update the {{Codeline|md5sum}} (if sources changed). You need to run {{Codeline|../makepkg -g >> PKGBUILD}} to do that, and should then move the new md5sum to its right position, after the source variable. 

Then you can follow the steps to add a new package, just skipping the first one (build package creation).

===Delete a package===
To delete a package or group of packages from a repository, run:

 remove.sh package_name

===Move a package===
To move a package or group of packages from a repository to another, run:

 move.sh package_name target_repo

==Maintenance==
===Update===
Don't forget to run the update script from time to time:
 cd buildroot
 ./update-buildsystem.sh